home *** CD-ROM | disk | FTP | other *** search
/ Amiga Plus Leser 15 / Amiga Plus Leser CD 15.iso / Tools / Development / MosaicSRC / libwww2 / HTAABrow.h < prev    next >
Encoding:
C/C++ Source or Header  |  2002-03-13  |  6.6 KB  |  181 lines
  1. /*                          BROWSER SIDE ACCESS AUTHORIZATION MODULE
  2.                                              
  3.    This module is the browser side interface to Access Authorization (AA) package.  It
  4.    contains code only for browser.
  5.    
  6.    Important to know about memory allocation:
  7.    
  8.    Routines in this module use dynamic allocation, but free automatically all the memory
  9.    reserved by them.
  10.    
  11.    Therefore the caller never has to (and never should) free() any object returned by
  12.    these functions.
  13.    
  14.    Therefore also all the strings returned by this package are only valid until the next
  15.    call to the same function is made. This approach is selected, because of the nature of
  16.    access authorization: no string returned by the package needs to be valid longer than
  17.    until the next call.
  18.    
  19.    This also makes it easy to plug the AA package in: you don't have to ponder whether to
  20.    free()something here or is it done somewhere else (because it is always done somewhere
  21.    else).
  22.    
  23.    The strings that the package needs to store are copied so the original strings given as
  24.    parameters to AA functions may be freed or modified with no side effects.
  25.    
  26.    Also note:The AA package does not free() anything else than what it has itself
  27.    allocated.
  28.    
  29.  */
  30.  
  31. #ifndef HTAABROW_H
  32. #define HTAABROW_H
  33.  
  34. #include "HTUtils.h"            /* BOOL, PARAMS, ARGS */
  35. #include "HTAAUtil.h"           /* Common parts of AA */
  36.  
  37.  
  38. #ifdef SHORT_NAMES
  39. #define HTAAcoAu        HTAA_composeAuth
  40. #define HTAAsRWA        HTAA_shouldRetryWithAuth
  41. #define HTAA_TWA        HTAA_TryWithAuth
  42. #endif /*SHORT_NAMES*/
  43.  
  44. /*
  45.  
  46. Routines for Browser Side Recording of AA Info
  47.  
  48.    Most of the browser-side AA is done by the following two functions (which are called
  49.    from file HTTP.c so the browsers using libwww only need to be linked with the new
  50.    library and not be changed at all):
  51.    
  52.       HTAA_composeAuth() composes the Authorization: line contents, if the AA package
  53.       thinks that the given document is protected. Otherwise this function returns NULL.
  54.       This function also calls the functions HTPrompt(),HTPromptPassword() and HTConfirm()
  55.       to get the username, password and some confirmation from the user.
  56.       
  57.       HTAA_shouldRetryWithAuth() determines whether to retry the request with AA or with a
  58.       new AA (in case username or password was misspelled).
  59.  
  60.       HTAA_TryWithAuth() sets up everything for an automatic first try with authentication.
  61.  
  62.       HTAA_ClearAuth() clears the currently allocated authentication record.
  63.       
  64.  */
  65.  
  66. /* PUBLIC                                               HTAA_composeAuth()
  67. **
  68. **      COMPOSE THE ENTIRE AUTHORIZATION HEADER LINE IF WE
  69. **      ALREADY KNOW, THAT THE HOST MIGHT REQUIRE AUTHORIZATION
  70. **
  71. ** ON ENTRY:
  72. **      hostname        is the hostname of the server.
  73. **      portnumber      is the portnumber in which the server runs.
  74. **      docname         is the pathname of the document (as in URL)
  75. **
  76. ** ON EXIT:
  77. **      returns NULL, if no authorization seems to be needed, or
  78. **              if it is the entire Authorization: line, e.g.
  79. **
  80. **                 "Authorization: basic username:password"
  81. **
  82. **              As usual, this string is automatically freed.
  83. */
  84. PUBLIC char *HTAA_composeAuth PARAMS((CONST char * hostname,
  85.                                       CONST int   portnumber,
  86.                                       CONST char * docname));
  87.  
  88.  
  89. /* BROWSER PUBLIC                               HTAA_shouldRetryWithAuth()
  90. **
  91. **              DETERMINES IF WE SHOULD RETRY THE SERVER
  92. **              WITH AUTHORIZATION
  93. **              (OR IF ALREADY RETRIED, WITH A DIFFERENT
  94. **              USERNAME AND/OR PASSWORD (IF MISSPELLED))
  95. ** ON ENTRY:
  96. **      start_of_headers is the first block already read from socket,
  97. **                      but status line skipped; i.e. points to the
  98. **                      start of the header section.
  99. **      length          is the remaining length of the first block.
  100. **      soc             is the socket to read the rest of server reply.
  101. **
  102. **                      This function should only be called when
  103. **                      server has replied with a 401 (Unauthorized)
  104. **                      status code.
  105. ** ON EXIT:
  106. **      returns         YES, if connection should be retried.
  107. **                           The node containing all the necessary
  108. **                           information is
  109. **                              * either constructed if it does not exist
  110. **                              * or password is reset to NULL to indicate
  111. **                                that username and password should be
  112. **                                reprompted when composing Authorization:
  113. **                                field (in function HTAA_composeAuth()).
  114. **                      NO, otherwise.
  115. */
  116. PUBLIC BOOL HTAA_shouldRetryWithAuth PARAMS((char *     start_of_headers,
  117.                                              int        length,
  118.                                              int        soc));
  119.  
  120.  
  121. #ifdef PEM_AUTH
  122. /* BROWSER PUBLIC                               HTAA_TryWithAuth()
  123. **
  124. **              SAYS WE KNOW WE SHOULD TRY THE SERVER
  125. **              WITH AUTHORIZATION RIGHT FROM THE START
  126. ** ON ENTRY:
  127. **      enctype         is the string we were given to determine
  128. **                      just what type of authorization we should ask for
  129. **                      from the start.
  130. **      entity          is the server identifier needed by some
  131. **                      types of authorization.
  132. **      action          is the url we are GETing or POSTing to.
  133. **
  134. **                      This function should only be called when
  135. **                      when we are responding to a form with ENCTYPE set.
  136. ** ON EXIT:
  137. **      returns         YES
  138. **                           The node containing all the necessary
  139. **                           information is constructed.
  140. **            NO
  141. **                 Client can't do this encryption type.
  142. */
  143. PUBLIC BOOL HTAA_TryWithAuth PARAMS((char *    enctype,
  144.                      char *    entity,
  145.                      char *    action));
  146.  
  147.  
  148. /*
  149.  
  150.  */
  151.  
  152. PUBLIC void HTAA_ClearAuth NOPARAMS;
  153. #endif /* PEM_AUTH */
  154.  
  155.  
  156. #ifdef PEM_AUTH
  157. /*
  158.  * PUBLIC                                               HTAA_makecommand()
  159.  * 
  160.  *              ENCRYPT AN HTTP REQUEST, AND ENCAPSULATE IT IN
  161.  *              A NEW HTTP PEM AUTHORIZED REQUEST
  162.  * 
  163.  * ON ENTRY:
  164.  *      command         the HTTP request
  165.  * 
  166.  * ON EXIT:
  167.  *      returns         the new HTTP request with PEM
  168.  * 
  169.  * Do not free this string. This function *requires* that the 
  170.  * HTAA_composeAuth function has been called prior to it.
  171.  * 
  172.  */
  173. PUBLIC char *HTAA_makecommand PARAMS((char * command, char **body, int *bl));
  174. #endif /* PEM_AUTH */
  175.  
  176.  
  177. #endif  /* NOT HTAABROW_H */
  178. /*
  179.  
  180.    End of file HTAABrow.h.  */
  181.